<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="generator" content="hevea 2.18">
<link rel="stylesheet" type="text/css" href="manual.css">
<title>Chapter&#XA0;23&#XA0;&#XA0;Fuzzing with afl-fuzz</title>
</head>
<body>
<a href="spacetime.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="plugins.html"><img src="next_motif.gif" alt="Next"></a>
<hr>
<h1 class="chapter" id="sec536">Chapter&#XA0;23&#XA0;&#XA0;Fuzzing with afl-fuzz</h1>
<ul>
<li><a href="afl-fuzz.html#sec537">23.1&#XA0;&#XA0;Overview</a>
</li><li><a href="afl-fuzz.html#sec538">23.2&#XA0;&#XA0;Generating instrumentation</a>
</li><li><a href="afl-fuzz.html#sec540">23.3&#XA0;&#XA0;Example</a>
</li></ul>

<h2 class="section" id="sec537">23.1&#XA0;&#XA0;Overview</h2>
<p>American fuzzy lop (&#X201C;afl-fuzz&#X201D;) is a <em>fuzzer</em>, a tool for
testing software by providing randomly-generated inputs, searching for
those inputs which cause the program to crash.</p><p>Unlike most fuzzers, afl-fuzz observes the internal behaviour of the
program being tested, and adjusts the test cases it generates to
trigger unexplored execution paths. As a result, test cases generated
by afl-fuzz cover more of the possible behaviours of the tested
program than other fuzzers.</p><p>This requires that programs to be tested are instrumented to
communicate with afl-fuzz. The native-code compiler &#X201C;ocamlopt&#X201D; can
generate such instrumentation, allowing afl-fuzz to be used against
programs written in OCaml.</p><p>For more information on afl-fuzz, see the website at
<a href="http://lcamtuf.coredump.cx/afl/">http://lcamtuf.coredump.cx/afl/</a>.
</p>
<h2 class="section" id="sec538">23.2&#XA0;&#XA0;Generating instrumentation</h2>
<p>The instrumentation that afl-fuzz requires is not generated by
default, and must be explicitly enabled, by passing the <span class="c003">-afl-instrument</span> option to <span class="c003">ocamlopt</span>.</p><p>To fuzz a large system without modifying build tools, OCaml&#X2019;s <span class="c003">configure</span> script also accepts the <span class="c003">afl-instrument</span> option. If
OCaml is configured with <span class="c003">afl-instrument</span>, then all programs
compiled by <span class="c003">ocamlopt</span> will be instrumented.</p>
<h3 class="subsection" id="sec539">23.2.1&#XA0;&#XA0;Advanced options</h3>
<p>In rare cases, it is useful to control the amount of instrumentation
generated. By passing the <span class="c003">-afl-inst-ratio N</span> argument to <span class="c003">ocamlopt</span> with <span class="c003">N</span> less than 100, instrumentation can be
generated for only N% of branches. (See the afl-fuzz documentation on
the parameter <span class="c003">AFL_INST_RATIO</span> for the precise effect of this).</p>
<h2 class="section" id="sec540">23.3&#XA0;&#XA0;Example</h2>
<p>As an example, we fuzz-test the following program, <span class="c003">readline.ml</span>:</p><pre>let _ =
  let s = read_line () in
  match Array.to_list (Array.init (String.length s) (String.get s)) with
    ['s'; 'e'; 'c'; 'r'; 'e'; 't'; ' '; 'c'; 'o'; 'd'; 'e'] -&gt; failwith "uh oh"
  | _ -&gt; ()
</pre><p>
There is a single input (the string &#X201C;secret code&#X201D;) which causes this
program to crash, but finding it by blind random search is infeasible.</p><p>Instead, we compile with afl-fuzz instrumentation enabled:
</p><pre>ocamlopt -afl-instrument readline.ml -o readline
</pre><p>Next, we run the program under afl-fuzz:
</p><pre>mkdir input
echo asdf &gt; input/testcase
mkdir output
afl-fuzz -i input -o output ./readline
</pre><p>By inspecting instrumentation output, the fuzzer finds the crashing input quickly.

</p>
<hr>
<a href="spacetime.html"><img src="previous_motif.gif" alt="Previous"></a>
<a href="index.html"><img src="contents_motif.gif" alt="Up"></a>
<a href="plugins.html"><img src="next_motif.gif" alt="Next"></a>
</body>
</html>
